Skip to content

fix(sync): change detection no longer takes git's index lock - #3338

Merged
colbymchenry merged 1 commit into
mainfrom
claude/issue-3295-git-optional-locks
Nov 18, 2026
Merged

colbymchenry merged 1 commit into
mainfrom
claude/issue-3295-git-optional-locks

Conversation

@colbymchenry

Copy link
Copy Markdown
Owner

Summary

Change detection no longer takes git's index lock. A git add in a pre-commit hook, a commit or a checkout that runs while CodeGraph syncs no longer fails with fatal: Unable to create '.git/index.lock': File exists.

Root cause

collectGitStatus (src/extraction/index.ts) runs git status --porcelain --no-renames -z -uall with git's optional locks on. In that mode git writes the stat info it refreshed back to the index, so it takes .git/index.lock right after the refresh and holds it through the diff and the whole untracked scan. A sync runs it twice; codegraph status and the MCP freshness checks run it once. The watcher wakes exactly when a commit, checkout or hook churns files, so the collisions cluster around the user's own git writes, as the issue's trace2 capture shows.

Fix

The status call, and the commit-range git diff beside it, run with GIT_OPTIONAL_LOCKS=0. That skips only the write-back: the output is identical, and the user's next git command refreshes the index itself. It is an environment variable rather than --no-optional-locks, which git before 2.15 rejects. The other git calls in change detection (ls-files, rev-parse, cat-file, config) never write the index.

Validation

  • New __tests__/git-status-optional-locks.test.ts (2 tests): getGitChangedFiles, a sync and a status check leave .git/index byte-identical. Both fail on main (the index is rewritten) and pass with the fix. Each first checks that a plain git status in the same state does rewrite it, so the assertion can't pass vacuously.
  • Repo with 10,000 tracked and 10,000 untracked files, polling for .git/index.lock while the CLI runs (Windows 11, git for Windows): main's build took it in 12/12 syncs and 8/8 status runs; this branch in 0/12 and 0/8.
  • Published 1.6.3 on the same repo with a git write loop (git update-index --refresh) running beside each sync: 3 of 176 writes failed with "index.lock: File exists", 0 of 175 with no sync running, 0 of 178 with GIT_OPTIONAL_LOCKS=0 set (what this branch sets).
  • Neighbouring suites git-changed-untracked-dir, git-index-currency, git-status-subdir-project, git-ignored-dirs-scope, cli-sync: 37 passed.
  • Full suite: see the READY report.

Fixes #3295

Thanks @iamclaudia-ai for the report, the trace2 capture and the suggested fix.

🤖 Generated with Claude Code

@colbymchenry
colbymchenry force-pushed the claude/issue-3295-git-optional-locks branch from d5208be to a999677 Compare November 17, 2026 22:32
Change detection runs `git status --porcelain --no-renames -z -uall` with
git's optional locks on. In that mode git writes the stat info it refreshed
back to the index, so it takes .git/index.lock right after the refresh and
holds it through the diff and the whole untracked scan. Every sync runs it
twice (the watcher's and codegraph sync), codegraph status and the MCP
freshness checks once each, and the watcher wakes exactly when a commit, a
checkout or a pre-commit hook churns files. A git write that started inside
that window failed at once with "index.lock: File exists".

The status call, and the commit-range diff beside it, now run with
GIT_OPTIONAL_LOCKS=0. That skips only the write-back: the output is the
same, and the user's next git command refreshes the index itself. It is an
environment variable rather than --no-optional-locks, which a git older
than 2.15 rejects. The other git calls change detection makes (ls-files,
rev-parse, cat-file, config) never write the index.

Validation:
- New git-status-optional-locks tests (2): getGitChangedFiles, a sync and a
  status check leave .git/index byte-identical. Both fail on main, where the
  index is rewritten, and pass with the fix. Each first checks that a plain
  git status in the same state does rewrite it.
- A repo with 10,000 tracked and 10,000 untracked files, polling for
  .git/index.lock while the CLI runs: main's build took it in 12 of 12
  syncs and 8 of 8 status runs, the fix in 0 of 12 and 0 of 8.
- Published 1.6.3 on the same repo, with a git write loop running beside
  each sync: 3 of 176 writes failed with "index.lock: File exists", 0 of
  175 with no sync running, and 0 of 178 with GIT_OPTIONAL_LOCKS=0 set.
- Neighbouring suites (git-changed-untracked-dir, git-index-currency,
  git-status-subdir-project, git-ignored-dirs-scope, cli-sync): 37 passed.

Fixes #3295

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Change detection's git status holds index.lock through its untracked scan and fails the user's git writes

1 participant